[DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511] by miliberlin · Pull Request #308 · checkly/docs

miliberlin · 2026-05-13T14:20:20Z

Documenting the cancellation behaviour. Let me know if anything should be removed or added elsewhere. Will need some more adjusting along the line (CLI version, etc.) and we need some more updates on the OpenAPI specs to correctly display the new endpoints in the API docs as documented here RED-511: [Docs] Update docs. Feel free to give it a read already.

Summary

Documents the Playwright Check Suite cancellation feature shipping under Allow cancellation of PWCS runs & test sessions (RED-511).

New pages

concepts/cancellation.mdx — explains what can be cancelled (check session vs. test session), how to cancel from UI/API/CLI, what happens after a run is cancelled (no alerts, excluded from metrics, no automated incidents), and the v1/v2 API versioning split.
api-reference/cancel/cancel-a-session.mdx — pulls POST /v1/cancel from the OpenAPI spec, with body content explaining the discriminated request body and the Playwright-only constraint.
api-reference/check-sessions/{trigger,retrieve,await-completion}-v2.mdx — three new pages mirroring the existing v1 reference pages. Each carries the v1 description forward and adds a "What's new in v2" Note.

Sidebar

docs.json gets a Cancel group in the API Reference tab, three new v2 entries under Check Sessions, and a concepts/cancellation entry under Concepts.

v1 deprecation markers

The three v1 check-session MDX pages now carry deprecated: true in frontmatter, matching the convention used by check-groups, check-results, checks, and triggers when a v2 replacement exists.

Cross-links and call-outs

concepts/results.mdx — short Note linking to the cancellation page.
communicate/alerts/configuration.mdx — Note in the configuration-hierarchy section stating cancelled runs never trigger alerts.
cli/checkly-{pw-test,test,trigger,deploy}.mdx — new "Cancelling a run" / "Cancelling a deploy" section describing Ctrl+C behaviour.

Needs verification before merge

See inline review comments on this PR — they pinpoint the exact lines.

CLI version availability in each of the four cli/checkly-*.mdx files. Each section has a {/* TODO */} comment and an Available in CLI vX.X+. placeholder. The Ctrl+C cancel logic lives in the checkly-cli repo, which I didn't read — Ferran should fill in (or remove) the version notes.
Ctrl+C UX accuracy. I wrote test/trigger/deploy as "cancel-or-detach with detach default" and pw-test as "no detach prompt; second Ctrl+C exits without waiting." This came from the project spec, not from reading the CLI source — please confirm.
Local Mintlify preview. Worth a npm run dev to confirm the four new OpenAPI-driven pages render cleanly and the new sidebar entries appear under the right groups.

Known follow-up — tracked separately

RED-512 — Empty/partial request/response examples on the new API reference pages.

Three distinct issues, all in the backend's OpenAPI generation:

POST /v1/cancel body renders as "any" — its request body refs #/x-alt-definitions/CancelCheckSession and #/x-alt-definitions/CancelTestSession. The schemas exist but live under x-alt-definitions instead of components/schemas, which Mintlify can't resolve.
All four endpoints' responses render as "string" — they declare schema: { type: "string" } with no $ref, no 2xx status code, and no error responses.
POST /v2/check-sessions/trigger has no request body schema at all — requestBody: {} is empty in the spec.

The fix lives in the backend route definitions (apps/backend/api/src/modules/public-api/check-sessions/v2/routes.ts and .../cancel/routes.ts) and will propagate to the docs repo via the next 48h CI sync. The docs PR can ship before that lands.

Test plan

npm run dev and visit /concepts/cancellation — copy reads cleanly, all links resolve.
Visit each of the four new API-reference pages — endpoint specs render from OpenAPI (examples will be partial until RED-512 ships).
Visit /concepts/results, /communicate/alerts/configuration, and the four cli/* pages — new sections appear in the right place.
Sidebar shows new entries: Concepts > Cancellation; API Reference > Cancel; API Reference > Check Sessions > the three v2 pages.
v1 check-session reference pages show the "deprecated" badge.
Fill in or remove the four Available in CLI vX.X+. placeholders.

🤖 Generated with Claude Code

- New concepts/cancellation.mdx covering cancellation surfaces, post-cancel flow, and API versioning - New api-reference/cancel/cancel-a-session.mdx for POST /v1/cancel - New v2 check-session reference pages (trigger, retrieve, await completion) - Sidebar entries in docs.json for the above - Cross-links from concepts/results.mdx, communicate/alerts/configuration.mdx - Ctrl+C cancellation sections in cli/checkly-{pw-test,test,trigger,deploy}.mdx Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

miliberlin · 2026-05-13T14:20:39Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships pw-test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships pw-test Ctrl+C handling (RED-375), or remove this Note if Ferran prefers a generic call-out. The Linear ticket is still in In Review.

miliberlin · 2026-05-13T14:20:41Z

+{/* TODO: confirm CLI version that ships pw-test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+Press <kbd>Ctrl</kbd>+<kbd>C</kbd> during a `checkly pw-test` run to cancel the test session. The CLI sends a cancel request and waits for the runner to stop. Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> a second time exits the CLI without waiting.


Verify the Ctrl+C UX matches what shipped: "no detach prompt; second Ctrl+C exits without waiting." I took this from the project spec (RED-375), not from reading the CLI source.

miliberlin · 2026-05-13T14:20:42Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly test Ctrl+C handling (was RED-373, marked Duplicate — verify it actually shipped), or remove this Note.

miliberlin · 2026-05-13T14:20:44Z

+{/* TODO: confirm CLI version that ships test Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+When you started the run with `--record`, pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session.


Verify "cancel or detach, detach is default" matches what shipped. RED-373 was marked Duplicate so I'm not 100% sure this is the final UX.

miliberlin · 2026-05-13T14:20:45Z

+## Cancelling a run
+
+{/* TODO: confirm CLI version that ships trigger Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly trigger Ctrl+C handling (RED-373 dup), or remove this Note.

miliberlin · 2026-05-13T14:20:47Z

+{/* TODO: confirm CLI version that ships trigger Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+When you started the run with `--record`, pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session.


Same UX question as in checkly-test.mdx — confirm "detach is the default" is accurate.

miliberlin · 2026-05-13T14:20:48Z

+## Cancelling a deploy
+
+{/* TODO: confirm CLI version that ships deploy Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>


Fill in the CLI version that ships checkly deploy Ctrl+C handling (RED-374 dup), or remove this Note.

miliberlin · 2026-05-13T14:20:52Z

+{/* TODO: confirm CLI version that ships deploy Ctrl+C handling and fill in the Note below. */}
+<Note>Available in CLI vX.X+.</Note>
+
+`checkly deploy` may run [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview) as part of post-deploy verification. Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> during that phase prompts you to either **cancel** the recorded check session or **detach** and let it finish in the background. Detach is the default.


Confirm: (1) checkly deploy actually runs PWCS as part of post-deploy verification today — is that universally true or only when configured? (2) "detach is the default" matches what shipped.

Match the convention used by check-groups and check-results: v1 MDX pages get deprecated: true when a v2 equivalent exists. Updates the matching ResponseField label in concepts/cancellation.mdx from backwards-compatible to deprecated for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The v2 OpenAPI entries have no description fields, so the auto-rendered pages were blank. Carry the v1 description text forward in the MDX body and add a What's new in v2 note covering the CANCELLED status value and isCancelled result flag. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The /v1/cancel OpenAPI entry has no description, so the auto-rendered page only showed the request schema. Add MDX body content explaining the discriminated body (checkSessionId vs testSessionId), the optional sequenceId narrowing, and the Playwright-only constraint, with a link out to the cancellation concept page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

timohuovinen · 2026-05-15T06:31:01Z

+The successful response of this endpoint is equivalent to the [retrieve a check session](/api-reference/check-sessions/retrieve-a-check-session-v2) endpoint's response for a completed check session.
+
+<Note>
+**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions.


for v1, cancelled is mapped to TIMED_OUT

Good point, added that!

The only v2-only addition is the CANCELLED status enum value; v1 maps cancelled sessions to TIMED_OUT. The isCancelled boolean on per-result objects is additive and present in both versions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

miliberlin commented May 13, 2026

View reviewed changes

miliberlin requested review from MariadeAnton, ferrandiaz and timohuovinen May 13, 2026 14:27

miliberlin and others added 3 commits May 13, 2026 16:31

miliberlin changed the title ~~docs: document PWCS cancellation feature [RED-511]~~ [DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511] May 13, 2026

miliberlin requested a review from hwartig May 13, 2026 14:59

timohuovinen reviewed May 15, 2026

View reviewed changes

timohuovinen approved these changes May 15, 2026

View reviewed changes

mintlify Bot deployed to staging May 15, 2026 13:08 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511]#308

[DO NOT MERGE!] docs: document PWCS cancellation feature [RED-511]#308
miliberlin wants to merge 5 commits into
mainfrom
michelle/red-511-docs-update-docs

miliberlin commented May 13, 2026 •

edited

Loading

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

miliberlin May 13, 2026

Uh oh!

timohuovinen May 15, 2026

Uh oh!

miliberlin May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

miliberlin commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New pages

Sidebar

v1 deprecation markers

Cross-links and call-outs

Needs verification before merge

Known follow-up — tracked separately

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

miliberlin commented May 13, 2026 •

edited

Loading